AddCollectionItemHdl

AddCollectionItemHdl
Header:	Collections.h		Carbon status:	Supported

Adds a new item to a collection or to replace an existing item in a collection, specifying the item’s variable-length data using a handle rather than a pointer and a data size.

OSErr AddCollectionItemHdl (
    Collection aCollection, 
    CollectionTag tag, 
    SInt32 id, 
    Handle itemData
);

aCollection: A reference to the collection you want to add the item to. The behavior of this function is undefined if you do not provide a reference to a valid collection object.
tag: The collection tag you want to associate with the new item.
id: The collection ID you want to associate with the new item.
itemData: A Macintosh Memory Manager handle to the item’s variable-length data. This function copies the information referenced by the itemData parameter into the new item; after calling this function, you may alter this information or free the memory referenced by this parameter without affecting the collection.

function result: A result code. If the aCollection collection already contains an item with the same collection tag and collection ID as specified in the tag and id parameters, this function removes the variable-length data from the original item and replaces it with the new data, unless the existing item is locked. If it is locked, this function returns a collectionItemLockedErr result code.

DISCUSSION

The AddCollectionItemHdl function adds an item to the collection referenced by the aCollection parameter. This new item contains:

the collection tag specified by the tag parameter
the collection ID specified by the id parameter
the attributes specified by the default attributes of the aCollection collection
the variable-length data specified by the itemData parameter

To add or replace a collection item using a pointer (rather than a handle) to the item’s variable-length data, use the AddCollectionItem function.

To replace a collection item using the item’s collection index (rather than the item’s collection tag and collection ID), use the ReplaceIndexedCollectionItemHdl function.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.